eDocs Home > BEA AquaLogic Data Services Platform Documentation > Data Services Developer's Guide > Contents

Data Service Keys

This topic describes what data service keys are and how they are used.

Overview

You are probably familiar with the concept of keys from relational databases, where a key is a set of one or more columns whose combined values are unique among all occurrences in a table.

When you create a physical data service, ALDSP computes keys by introspecting the physical data sources. A physical data service key can have one or more fields, which are elements taken from the service's return type. Tangibly, a key is defined as an XML schema in an XSD file.

You can see the physical data service keys in your dataspace project in Studio. They appear in schema files with names such as:

Physical Data Service Keys in Studio

In the generated XSD file, a key for a physical data service looks something like this.

Key for the CUSTOMER Table

<?xml version="1.0" encoding="UTF-8" ?>
<xs:schema targetNamespace="ld:physical/CUSTOMER" xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="CUSTOMER_KEY">
      <xs:complexType>
         <xs:sequence>
            <xs:element name="CUSTOMER_ID" type="xs:string"/>
         </xs:sequence>
      </xs:complexType>
   </xs:element>
</xs:schema>

In this case, CUSTOMER_ID is the primary key in a relational table named CUSTOMER.

In a logical data service, a key also uniquely defines a data record. However, the data in the record can originate from multiple data sources of different types and can have a structure unlike the underlying physical data sources.

For a logical entity service, you must create the key. You can choose one of these options:

• Have ALDSP generate the key based on the service's primary read function. ALDSP generates a minimal key.
• Select the fields that make up the key. The elements that comprise the key must have a cardinality of 0 or 1 in the service's return type (with maxOccurs="1" or maxOccurs="0", but not maxOccurs="unbounded").

Parts of a Key

Suppose a logical service has a nested return type where a parent element with single cardinality can have multiple child elements, say one CUSTOMER element with many CUSTOMER_ORDER child elements.

A Nested Return Type with a One-to-Many Relationship

<?xml version="1.0" encoding="UTF-8" ?>
<xs:schema targetNamespace="ld:logical/CustomersAndOrders" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="CustomersAndOrders">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="CUSTOMER">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="CUSTOMER_ID" type="xs:string"/>
              <xs:element name="FIRST_NAME" type="xs:string"/>
              <xs:element name="LAST_NAME" type="xs:string"/>
              <xs:element name="SSN" type="xs:string" minOccurs="0"/>
              <xs:element name="CUSTOMER_ORDER" maxOccurs="unbounded">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element name="ORDER_ID" type="xs:string"/>
                    <xs:element name="C_ID" type="xs:string"/>
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

This is the key that ALDSP auto-generates from this return type, from the unique CUSTOMER_ID field:

An Auto-Generated Simple Key

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="ld:logical/CustomerOrder" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="CustomersAndOrders_KEY">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="CUSTOMER_ID" type="xs:string"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

If you choose to select the key fields, you need to use a unique field or fields with single cardinality. You can choose CUSTOMER_ID or SSN, or both. You cannot define the key on ORDER_ID or C_ID, because they belong to the CUSTOMER_ORDER element, which has multiple cardinality.

If you choose SSN, the key schema file looks like this.

A Manually Selected Key

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="ld:logical/CustomerOrder" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="CustomersAndOrders_KEY">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="SSN" maxOccurs="1" minOccurs="0" type="xs:string"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

A data service key has distinct parts:

• A selector. A key selector identifies a collection of data records. A key's selector is the element that contains the key field in the service's return type. You can see a key's selector in the Manage Key dialog when you create the key (below, it's the CUSTOMER element):
   

  

   
  You can see that the CUSTOMER element is the root element of the return type:
   

  

• The key fields. The fields that make up the key uniquely identify an element in the collection. For example, one customer identified by a CUSTOMER_ID value. Within ALDSP, a key field is stored as a path which must not contain any repeating elements. Therefore, you cannot use elements with multiple cardinality in keys.

Composite Keys

With a logical service, a key can also be a composite key of multiple elements, as long as the elements have single cardinality in the return type. This is especially easy with a flat return type.

A Flat, Non-Nested Return Type

<?xml version="1.0" encoding="UTF-8" ?>
<xs:schema targetNamespace="ld:logical/MyFlatOne" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="CUSTOMERORDER">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="CUSTOMER_ID" type="xs:string"/>
        <xs:element name="FIRST_NAME" type="xs:string"/>
        <xs:element name="LAST_NAME" type="xs:string"/>
        <xs:element name="EMAIL_ADDRESS" type="xs:string"/>
        <xs:element name="ORDER_ID" type="xs:string"/>
        <xs:element name="ORDER_DT" type="xs:date"/>
        <xs:element name="TOTAL_ORDER_AMT" type="xs:decimal"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

ALDSP auto-generates a composite key using the key fields from the underlying physical data sources (in this example, CUSTOMER_ID and ORDER_ID). The composite key generated from this return type is shown below.

An Auto-Generated Composite Key 

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="ld:logical/MyFlatOne" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="MyFlatOne_KEY">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="CUSTOMER_ID" type="xs:string"/>
        <xs:element name="ORDER_ID" type="xs:string"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

This key allows you to identify a unique combination of Customer and Order, that is, one order for one customer.

See Also

How Tos

• Create Logical Data Service Keys